home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 April: Mac OS SDK / Dev.CD Apr 96 SDK / Dev.CD Apr 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc / Documentation / Tech Notes & Articles / Recipes / Standards / Parameters & OpenDoc < prev    next >
Encoding:
Text File  |  1995-07-11  |  5.7 KB  |  254 lines  |  [TEXT/ttxt]
  1. OpenDoc™ Recipes
  2.  
  3. Parameter passing in OpenDoc
  4. By The OpenDoc Design Team
  5. July 11, 1995.
  6.  
  7. © 1993-1995  Apple Computer, Inc. All Rights Reserved.
  8. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  9. Mac and OpenDoc are trademarks of Apple Computer, Inc.
  10.  
  11. Changes since DR2
  12.  
  13. 1) Removed sequence/inout.
  14.  
  15. Overview
  16.  
  17. This document outlines the cases where parameter passing can be problematic:
  18. - Object Reference
  19. - string/in, string/out, string/return
  20. - sequence/in, sequence/out, sequence/return
  21.  
  22. string/inout is not discussed here because there does not seem to be any need for it.
  23.  
  24. Object Reference
  25.  
  26. - Do not use ODObject/inout.
  27.  
  28.  
  29. string or ODISOString
  30.  
  31. 1) in parameter:
  32.  
  33. Example: void StorageUnit::SetType(in ODValueType valueType);
  34.  
  35. Client:  Provides and releases the storage for the in parameter.
  36.  
  37. // First case using constant
  38. const ODValueType kMyType = “MyValueType”;
  39. su->SetType(ev, kMyType);
  40. // In this case, we don’t need to explicitly dispose of the string.
  41. .....
  42.  
  43. // Second case using heap memory
  44. ODULong strLength = ODISOStrLength(kMyType) + 1;
  45. ODPtr buffer = ODNewPtr(strLength);
  46. memcpy(kMyType, buffer, strLength);
  47. su->SetType(ev, buffer);
  48. // In this case, we have to dispose of the string
  49. ODDisposePtr(buffer);
  50.  
  51. OpenDoc: Cannot store the incoming pointer. If it needs to store the string, it has to make a copy.
  52.  
  53. SOM_Scope void  SOMLINK ODStorageUnitSetType(ODStorageUnit *somSelf, Environment *ev,
  54.     ODType type)
  55. {
  56.     ......
  57.  
  58.     ODISOStrCopy(type, _fMyType);
  59.     
  60.     // Do NOT dispose of memory.
  61. }
  62.  
  63.  
  64. 2) Out parameter
  65.  
  66. Example: ODBoolean ODSession::GetType(in ODTypeToken token,  out ODType type);
  67.  
  68. Client: Releases the storage for the out parameter.
  69.  
  70. ODType type = kODNULL;
  71.  
  72. // Call OpenDoc
  73. ODBoolean boolean = session->GetType(ev, token, &type);
  74.  
  75. // Use it.
  76. .......
  77.  
  78. // Client is responsible for disposing the out parameter.
  79. ODDisposePtr(type);
  80.  
  81. OpenDoc: OpenDoc provides the storage for the out parameter.
  82.  
  83. SOM_Scope ODBoolean  SOMLINK ODBaseSessionGetType(ODBaseSession *somSelf, Environment *ev,
  84.         ODTypeToken token, ODType* returnType)
  85. {
  86.      ....
  87.  
  88.     // Look up type using token
  89.     ODType myType = ......
  90.  
  91.     // Allocate memory for the returned type.
  92.     // Make sure that you make a copy of it before returning.
  93.     *returnType = ODNewPtr(sizeOfMyType);
  94.  
  95.     // Copying the type
  96.     ODISOStrCopy(myType, *returnType);
  97.     
  98.     return kODTrue;
  99. }
  100.  
  101.  
  102. 3) function return
  103.  
  104. Example: ODValueType  ODStorageUnit::GetType();
  105.  
  106. Client:  Releases the storage for the function return.
  107.  
  108. // Call OpenDoc
  109. ODValueType valueType = su->GetType(ev);
  110.  
  111. // Use it.
  112. .......
  113.  
  114. // Client is responsible for disposing the returned result.
  115. ODDisposePtr(valueType);
  116.  
  117. OpenDoc: OpenDoc provides the storage for the returned result.
  118.  
  119. SOM_Scope ODValueType  SOMLINK ODStorageUnitGetType(ODStorageUnit *somSelf, Environment *ev)
  120. {
  121.     ......
  122.  
  123.     // Allocate memory for the returned type.
  124.     ODValueType returnValueType = ODNewPtr(sizeOfMyValueType);
  125.  
  126.     // Copying the value type
  127.     ODISOStrCopy(myValueType, returnValueType);
  128.  
  129.     // Return the value type
  130.     return returnValueType;
  131. }
  132.  
  133.  
  134. sequence
  135.  
  136. 1) in parameter:
  137.  
  138. Example: void ODStorageUnit::SetValue(in ODByteArray value);
  139.  
  140. Client: Provides and releases the storage for the in parameter.
  141.  
  142. ODByteArray ba;
  143. ba._length = length;
  144. ba._maximum = maximum;
  145. ba._buffer = buffer;
  146. su->SetValue(ev, &ba);
  147.  
  148. // Client is also responsible for deallocating the memory for the buffer.
  149. // That means the buffer is not consumed by the call.
  150.  
  151. OpenDoc: Cannot store the incoming pointer. If it needs to store the string, it has to make a copy.
  152.  
  153. SOM_Scope void  SOMLINK ODStorageUnitSetValue(ODStorageUnit *somSelf, Environment *ev,
  154.     ODByteArray* value)
  155. {
  156.     ......
  157.  
  158.     memcpy(value->_buffer, _fMyBuffer, value->_length);
  159.     
  160.     // Do NOT dispose of memory.
  161. }
  162.  
  163. 2) Out parameter
  164.  
  165. Example: ODBoolean ODValueNameSpace::GetEntry(in ODISOStr key, out ODByteArray value);
  166.  
  167.  
  168. Client: 
  169. -provides the storage for the structure which contains the description of the sequence.
  170. - manages release of the storage and the descriptor.
  171.  
  172. // Create byte array
  173. ODByteArray ba;
  174.  
  175. // Call OpenDoc
  176. valueNameSpace->GetValue(ev, key, &ba);
  177.  
  178. // Use data returned by OpenDoc
  179. ......
  180.  
  181. // Dispose the buffer returned by OpenDoc.
  182. ODDisposePtr(ba._buffer);
  183.  
  184. // ODByteArray struct gets disposed when the function exits.
  185.  
  186. OpenDoc:
  187. - prvoides storage for the values returned
  188. - puts the pointers to this storage in the descriptor structures.
  189.  
  190. SOM_Scope ODBoolean  SOMLINK ODValueNameSpaceGetEntry(ODValueNameSpace *somSelf,
  191.     Environment *ev, ODISOStr key, ODByteArray* value)
  192. {
  193.     // Look up the entry using key
  194.     ......
  195.     
  196.     // determine actual length to be returned
  197.     actualLength = ......
  198.  
  199.     // Allocate buffer for data to be returned.
  200.     buffer = ODNewPtr(actualLength);
  201.  
  202.     // Set the return byte array correctly.
  203.     value->_length = actualLength;
  204.     value->_maximum = actualLength;
  205.     value->_buffer = buffer;
  206.  
  207.     .....
  208.  
  209.     return kODTrue;
  210. }
  211.  
  212. 3) Return result
  213.  
  214. Example: ODByteArray ODLinkSpec::GetPartData();
  215.  
  216. Client: 
  217. -provides the storage for the structure which contains the description of the sequence.
  218. - manages release of the storage and the descriptor.
  219.  
  220. // Call OpenDoc
  221. ODByteArray ba = linkSpec->GetPartData(ev);
  222.  
  223. // Use data returned by OpenDoc
  224. ......
  225.  
  226. // Dispose the buffer returned by OpenDoc when done.
  227. ODDisposePtr(ba._buffer);
  228.  
  229. OpenDoc:
  230. - prvoides storage for the values returned
  231. - puts the pointers to this storage in the descriptor structures.
  232.  
  233. SOM_Scope ODByteArray  SOMLINK ODLinkSpecGetPartData(ODStorageUnit *somSelf, Environment *ev)
  234. {
  235.     ......
  236.     // set up the local byte array
  237.     ODByteArray ba;
  238.  
  239.     // determine actual length to be returned
  240.     actualLength = ......
  241.  
  242.     // Allocate buffer for data to be returned.
  243.     buffer = ODNewPtr(actualLength);
  244.  
  245.     // Set the return byte array correctly.
  246.     ba._length = actualLength;
  247.     ba._maximum = actualLength;
  248.     ba._buffer = buffer;
  249.  
  250.     .....
  251.  
  252.     return ba;
  253. }
  254.